chore(cli): deprecate SDK-first initialization by tamirdresher · Pull Request #1968 · bradygaster/squad

tamirdresher · 2026-09-01T07:40:49Z

Summary

deprecate squad init --sdk and announce its removal in v2
preserve the supported programmatic SDK and squad build compatibility for existing squad.config.ts projects
recommend markdown-first initialization across CLI help, READMEs, onboarding, navigation, role guidance, and active references
document the accepted decision and include the required CLI changeset

Closes #341
Closes #347

Testing

npm run build
npm exec vitest run test/cli/init.test.ts test/cli/command-help.test.ts (32 passed)
full docs build: 701 pages and Pagefind index generated successfully
fresh code review found no remaining issues

## Summary - Warn when users invoke squad init --sdk and announce removal in v2 - Keep squad build compatibility for existing squad.config.ts projects - Update English and Chinese guidance to recommend markdown-first initialization - Document the accepted deprecation decision and add a CLI changeset Closes bradygaster#341 Closes bradygaster#347 ## Test Plan - npm run build - npm exec vitest run test/cli/init.test.ts test/cli/command-help.test.ts - npm exec markdownlint-cli2 on updated documentation Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-09-01T07:41:00Z

🏗️ Architectural Review

⚠️ Architectural review: 1 warning(s).

Severity	Category	Finding	Files
🟡 warning	bootstrap-area	2 file(s) in the bootstrap area (packages/squad-cli/src/cli/core/) were modified. These files must maintain zero external dependencies. Review carefully.	`packages/squad-cli/src/cli/core/command-help.ts`, `packages/squad-cli/src/cli/core/init.ts`

Automated architectural review — informational only.

github-actions · 2026-09-01T07:41:02Z

🟡 Impact Analysis — PR #1968

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	19
Files added	2
Files modified	17
Files deleted	0
Modules touched	4

🎯 Risk Factors

19 files changed (6-20 → MEDIUM)
4 modules touched (2-4 → MEDIUM)

📦 Modules Affected

docs (11 files)

docs/proposals/deprecate-sdk-init.md
docs/src/content/blog/024-v0823-release.md
docs/src/content/docs/concepts/what-is-squad.md
docs/src/content/docs/features/built-in-roles.md
docs/src/content/docs/get-started/installation.md
docs/src/content/docs/guide.md
docs/src/content/docs/reference/config.md
docs/src/content/docs/reference/sdk.md
docs/src/content/docs/sdk-first-mode.md
docs/src/content/docs/whatsnew.md
docs/src/navigation.ts

root (3 files)

.changeset/deprecate-sdk-init.md
README.md
README.zh.md

squad-cli (3 files)

packages/squad-cli/src/cli-entry.ts
packages/squad-cli/src/cli/core/command-help.ts
packages/squad-cli/src/cli/core/init.ts

tests (2 files)

test/cli/command-help.test.ts
test/cli/init.test.ts

This report is generated automatically for every PR. See #733 for details.

github-actions · 2026-09-01T07:41:09Z

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit bf8ad86

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 4 item(s) to address before review

Status	Check	Details
❌	Single commit	7 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	⚠️ PR includes 1 docs/proposals/ file(s) — ensure these are intentional
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	1 unresolved Copilot thread(s) — fix and resolve before merging
❌	CI passing	6 check(s) still running

Files Changed (19 files, +112 −130)

File	+/−
`.changeset/deprecate-sdk-init.md`	+5 −0
`README.md`	+3 −18
`README.zh.md`	+3 −18
`docs/proposals/deprecate-sdk-init.md`	+24 −0
`docs/src/content/blog/024-v0823-release.md`	+2 −0
`docs/src/content/docs/concepts/what-is-squad.md`	+2 −3
`docs/src/content/docs/features/built-in-roles.md`	+3 −1
`docs/src/content/docs/get-started/installation.md`	+2 −0
`docs/src/content/docs/guide.md`	+11 −44
`docs/src/content/docs/reference/config.md`	+4 −2
`docs/src/content/docs/reference/sdk.md`	+3 −1
`docs/src/content/docs/sdk-first-mode.md`	+14 −37
`docs/src/content/docs/whatsnew.md`	+2 −0
`docs/src/navigation.ts`	+1 −1
`packages/squad-cli/src/cli-entry.ts`	+1 −2
`packages/squad-cli/src/cli/core/command-help.ts`	+1 −1
`packages/squad-cli/src/cli/core/init.ts`	+7 −1
`test/cli/command-help.test.ts`	+8 −0
`test/cli/init.test.ts`	+16 −1

Total: +112 −130

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

Copilot

Copilot review overview

🟡 Changes recommended

The docs introduce a new [!CAUTION] admonition syntax and the init test mixes package vs source import paths, both of which reduce consistency and confidence in rendered output and test representativeness.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review tier: Lite
Findings: 1 · 3

New issues introduced by this change (4)

Severity	Finding
	`test/cli/init.test.ts` — This test file imports runInit from the published entrypoint and also imports the same module via a…
	`docs/src/content/docs/sdk-first-mode.md` — The docs currently use blockquote callouts like `> ⚠️ Experimental — ...`. The new `>…
	`docs/src/content/docs/reference/sdk.md` — This page introduces `> [!CAUTION]` for an admonition, but the surrounding docs typically use `> ⚠️…
	`docs/src/content/docs/reference/config.md` — `[!CAUTION]` isn’t used elsewhere in these docs; existing callouts use the `> ⚠️ Experimental —…

What changed in this PR

This PR deprecates SDK-first initialization (squad init --sdk) across the CLI, help output, and documentation, while keeping squad build working for existing squad.config.ts projects during the transition to v2.

Changes:

Add a deprecation warning path when runInit(..., { sdk: true }) is used, while keeping the flag functional.
Update CLI help text (top-level and init help) and strengthen tests to assert deprecation messaging.
Update docs/READMEs to recommend markdown-first initialization and record the accepted decision + include a CLI changeset.

File	Description
`packages/squad-cli/src/cli/core/init.ts`	Emits deprecation warning when `--sdk` is used while preserving compatibility.
`packages/squad-cli/src/cli/core/command-help.ts`	Marks `init --sdk` as deprecated in command help output.
`packages/squad-cli/src/cli-entry.ts`	Marks `--sdk` as deprecated in top-level CLI help text.
`test/cli/init.test.ts`	Adds coverage for the deprecation warning + compatibility behavior.
`test/cli/command-help.test.ts`	Asserts `--sdk` deprecation is reflected in help output.
`README.md`	Updates SDK-first section to “Deprecated” and points to legacy compatibility docs.
`README.zh.md`	Chinese README: same deprecation shift + legacy compatibility pointer.
`docs/src/content/docs/sdk-first-mode.md`	Reframes SDK-first docs as legacy/compatibility-focused and discourages new adoption.
`docs/src/content/docs/reference/sdk.md`	Adds deprecation notice for SDK-first builders.
`docs/src/content/docs/reference/config.md`	Adds deprecation notice for `squad.config.ts` reference.
`docs/src/content/docs/guide.md`	Updates guide to label SDK-first mode and related commands as deprecated/legacy.
`docs/src/content/docs/concepts/what-is-squad.md`	Reorients concept framing to markdown-first and notes legacy deprecation.
`docs/proposals/deprecate-sdk-init.md`	Records the accepted decision and rationale for deprecating `--sdk` init.
`.changeset/deprecate-sdk-init.md`	Patch changeset for `@bradygaster/squad-cli` documenting the deprecation.

Suppressed comments (1)

test/cli/init.test.ts:59

Use the same runInit import used by the rest of the file when exercising --sdk deprecation behavior, so this test validates the public entrypoint rather than a second import path.

    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
    try {
      await runInitFromSource(TEST_ROOT, { sdk: true });

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

bradygaster

kill it with fire and never allow me to make a bad decision like this without significant ridicule.

## Summary - Address Copilot review feedback by using the public init import and established warning callouts - Remove SDK-first recommendations from active onboarding and role documentation - Label the compatibility guide clearly in navigation and references ## Test Plan - npm run build - npm exec vitest run test/cli/init.test.ts test/cli/command-help.test.ts - npm run docs:build Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Restore the role guide's existing line endings while keeping the SDK-first deprecation notice. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

…k-init # Conflicts: # docs/src/content/docs/get-started/install-comprehensive.md # docs/src/content/docs/get-started/installation.md

Copilot

Copilot encountered an error: Your billing is not configured or you have Copilot licenses from multiple standalone organizations or enterprises. To use premium requests, select a billing entity via the GitHub site, under Settings > Copilot > Features.

Copilot

Copilot review overview

🟢 Approval recommended

The functional behavior remains compatible, tests cover the deprecation messaging, and the remaining feedback is limited to small documentation/help-text consistency nits.

Review tier: Lite
Findings: 2

New issues introduced by this change (2)

Severity	Finding
	`docs/src/content/docs/sdk-first-mode.md` — The page is now presented throughout the docs/nav as “Legacy SDK-First Mode”, but the H1 still…
	`packages/squad-cli/src/cli/core/command-help.ts` — The init subcommand help uses a different deprecation style/casing (“Deprecated: …”) than other…

Clarify that the deprecation applies to squad.config.ts file authoring, not the supported programmatic SDK APIs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot review overview

🟡 Changes recommended

Prominent user-facing docs still describe SDK-first as current/recommended (e.g., “What’s New” current release notes), which conflicts with the PR’s stated goal of recommending markdown-first across active references.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review tier: Lite
Findings: 3

New issues introduced by this change (1)

Severity	Finding
	`docs/src/content/docs/guide.md` — This guide correctly marks `squad init --sdk` as deprecated, but there are still prominent docs…

Pre-existing issues (2)

Severity	Finding
	`packages/squad-cli/src/cli/core/command-help.ts` — The init subcommand help uses a different deprecation style/casing (“Deprecated: …”) than other… View comment
	`docs/src/content/docs/sdk-first-mode.md` — The page is now presented throughout the docs/nav as “Legacy SDK-First Mode”, but the H1 still… View comment

Suppressed comments (1)

docs/src/content/docs/sdk-first-mode.md:1

The page is now positioned as “legacy”, but the H1 still reads “SDK-First Squad Mode”. This makes the navigation/title inconsistent (e.g., sidebar says “Legacy SDK-First Mode”) and can confuse readers about what’s recommended.

# SDK-First Squad Mode

Align legacy guide and CLI help naming, and mark historical SDK-first release pages with the current deprecation status. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

…k-init

tamirdresher requested a review from bradygaster as a code owner September 1, 2026 07:40

Copilot AI lite review requested due to automatic review settings September 1, 2026 07:40

Copilot started reviewing on behalf of tamirdresher September 1, 2026 07:41 View session

Copilot AI reviewed Sep 1, 2026

View reviewed changes

Comment thread test/cli/init.test.ts

Comment thread docs/src/content/docs/sdk-first-mode.md Outdated

Comment thread docs/src/content/docs/reference/sdk.md Outdated

Comment thread docs/src/content/docs/reference/config.md Outdated

bradygaster approved these changes Sep 1, 2026

View reviewed changes

bradygaster approved these changes Sep 3, 2026

View reviewed changes

Copilot AI added 3 commits September 3, 2026 12:26

chore(docs): preserve role guide line endings

dffdd43

Restore the role guide's existing line endings while keeping the SDK-first deprecation notice. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Merge remote-tracking branch 'origin/dev' into squad/341-deprecate-sd…

2e07ebd

…k-init # Conflicts: # docs/src/content/docs/get-started/install-comprehensive.md # docs/src/content/docs/get-started/installation.md

tamirdresher requested a lite review from Copilot September 3, 2026 09:39

Copilot AI reviewed Sep 3, 2026

tamirdresher requested a lite review from Copilot September 3, 2026 14:09

Copilot started reviewing on behalf of tamirdresher September 3, 2026 14:09 View session

Copilot AI reviewed Sep 3, 2026

View reviewed changes

Comment thread docs/src/content/docs/sdk-first-mode.md Outdated

Comment thread packages/squad-cli/src/cli/core/command-help.ts Outdated

docs: clarify sdk deprecation scope

05939b6

Clarify that the deprecation applies to squad.config.ts file authoring, not the supported programmatic SDK APIs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

tamirdresher requested a lite review from Copilot September 3, 2026 16:47

Copilot started reviewing on behalf of tamirdresher September 3, 2026 16:48 View session

Copilot AI reviewed Sep 3, 2026

View reviewed changes

Comment thread docs/src/content/docs/guide.md

Copilot AI added 2 commits September 3, 2026 20:00

docs: resolve final sdk deprecation review

8d993e7

Align legacy guide and CLI help naming, and mark historical SDK-first release pages with the current deprecation status. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Merge remote-tracking branch 'origin/dev' into squad/341-deprecate-sd…

bf8ad86

…k-init

Navigation Menu

chore(cli): deprecate SDK-first initialization - #1968

chore(cli): deprecate SDK-first initialization#1968
tamirdresher wants to merge 7 commits into
bradygaster:devfrom
tamirdresher:squad/341-deprecate-sdk-init

tamirdresher commented Sep 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 1, 2026

Uh oh!

github-actions Bot commented Sep 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bradygaster left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

tamirdresher commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Uh oh!

github-actions Bot commented Sep 1, 2026

🏗️ Architectural Review

Uh oh!

github-actions Bot commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Impact Analysis — PR #1968

📊 Summary

🎯 Risk Factors

📦 Modules Affected

Uh oh!

github-actions Bot commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛫 PR Readiness Check

⚠️ 4 item(s) to address before review

Files Changed (19 files, +112 −130)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bradygaster left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tamirdresher commented Sep 1, 2026 •

edited

Loading

github-actions Bot commented Sep 1, 2026 •

edited

Loading

github-actions Bot commented Sep 1, 2026 •

edited

Loading